---
title: Externals
sort: 15
contributors:
  - sokra
  - skipjack
  - pksjce
  - fadysamirsadek
  - byzyk
  - zefman
  - Mistyyyy
  - jamesgeorge007
  - tanhauhau
  - snitin315
  - beejunk
  - EugeneHlushko
  - chenxsan
  - pranshuchittora
  - kinetifex
  - anshumanv
  - SaulSilver
  - fi3ework
---

The `externals` configuration option provides a way of excluding dependencies from the output bundles. Instead, the created bundle relies on that dependency to be present in the consumer's (any end-user application) environment. This feature is typically most useful to **library developers**, however there are a variety of applications for it.

## externals

`string` `object` `function` `RegExp` `[string, object, function, RegExp]`

**Prevent bundling** of certain `import`ed packages and instead retrieve these _external dependencies_ at runtime.

For example, to include [jQuery](https://jquery.com/) from a CDN instead of bundling it:

**index.html**

```html
<script
  src="https://code.jquery.com/jquery-3.1.0.js"
  integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk="
  crossorigin="anonymous"
></script>
```

**webpack.config.js**

```javascript
module.exports = {
  //...
  externals: {
    jquery: 'jQuery',
  },
};
```

This leaves any dependent modules unchanged, i.e. the code shown below will still work:

```javascript
import $ from 'jquery';

$('.my-element').animate(/* ... */);
```

The property name `jquery` specified under `externals` in the above `webpack.config.js` indicates that the module `jquery` in `import $ from 'jquery'` should be excluded from bundling. In order to replace this module, the value `jQuery` will be used to retrieve a global `jQuery` variable, as the default external library type is `var`, see [externalsType](#externalstype).

While we showed an example consuming external global variable above, the external can actually be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in [externalsType](#externalstype).

### string

Depending on the [externalsType](#externalstype), this could be the name of the global variable (see [`'global'`](#externalstypeglobal), [`'this'`](#externalstypethis), [`'var'`](#externalstypevar), [`'window'`](#externalstypewindow)) or the name of the module (see `amd`, [`commonjs`](#externalstypecommonjs), [`module`](#externalstypemodule), `umd`).

You can also use the shortcut syntax if you're defining only 1 external:

```javascript
module.exports = {
  //...
  externals: 'jquery',
};
```

equals to

```javascript
module.exports = {
  //...
  externals: {
    jquery: 'jquery',
  },
};
```

You can specify the [external library type](#externalstype) to the external with the `${externalsType} ${libraryName}` syntax. It will override the default external library type specified in the [externalsType](#externalstype) option.

For example, if the external library is a [CommonJS module](#externalstypecommonjs), you can specify

```javascript
module.exports = {
  //...
  externals: {
    jquery: 'commonjs jquery',
  },
};
```

### [string]

```javascript
module.exports = {
  //...
  externals: {
    subtract: ['./math', 'subtract'],
  },
};
```

`subtract: ['./math', 'subtract']` allows you select part of a module, where `./math` is the module and your bundle only requires the subset under the `subtract` variable.

When the `externalsType` is `commonjs`, this example would translate to `require('./math').subtract;` while when the `externalsType` is `window`, this example would translate to `window["./math"]["subtract"];`

Similar to the [string syntax](#string), you can specify the external library type with the `${externalsType} ${libraryName}` syntax, in the first item of the array, for example:

```javascript
module.exports = {
  //...
  externals: {
    subtract: ['commonjs ./math', 'subtract'],
  },
};
```

### object

W> An object with `{ root, amd, commonjs, ... }` is only allowed for [`libraryTarget: 'umd'`](/configuration/output/#outputlibrarytarget) and [`externalsType: 'umd'`](#externalstype). It's not allowed for other library targets.

```javascript
module.exports = {
  //...
  externals: {
    react: 'react',
  },

  // or

  externals: {
    lodash: {
      commonjs: 'lodash',
      amd: 'lodash',
      root: '_', // indicates global variable
    },
  },

  // or

  externals: {
    subtract: {
      root: ['math', 'subtract'],
    },
  },
};
```

This syntax is used to describe all the possible ways that an external library can be made available. `lodash` here is available as `lodash` under AMD and CommonJS module systems but available as `_` in a global variable form. `subtract` here is available via the property `subtract` under the global `math` object (e.g. `window['math']['subtract']`).

### function

- `function ({ context, request, contextInfo, getResolve }, callback)`
- `function ({ context, request, contextInfo, getResolve }) => promise` <Badge text='5.15.0+' />

It might be useful to define your own function to control the behavior of what you want to externalize from webpack. [webpack-node-externals](https://www.npmjs.com/package/webpack-node-externals), for example, excludes all modules from the `node_modules` directory and provides options to allowlist packages.

Here're arguments the function can receive:

- `ctx` (`object`): Object containing details of the file.
  - `ctx.context` (`string`): The directory of the file which contains the import.
  - `ctx.request` (`string`): The import path being requested.
  - `ctx.contextInfo` (`object`): Contains information about the issuer (e.g. the layer and compiler)
  - `ctx.getResolve` <Badge text='5.15.0+' />: Get a resolve function with the current resolver options.
- `callback` (`function (err, result, type)`): Callback function used to indicate how the module should be externalized.

The callback function takes three arguments:

- `err` (`Error`): Used to indicate if there has been an error while externalizing the import. If there is an error, this should be the only parameter used.
- `result` (`string` `[string]` `object`): Describes the external module with the other external formats ([`string`](#string), [`[string]`](#string-1), or [`object`](#object))
- `type` (`string`): Optional parameter that indicates the module [external type](#externalstype) (if it has not already been indicated in the `result` parameter).

As an example, to externalize all imports where the import path matches a regular expression you could do the following:

**webpack.config.js**

```javascript
module.exports = {
  //...
  externals: [
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        // Externalize to a commonjs module using the request path
        return callback(null, 'commonjs ' + request);
      }

      // Continue without externalizing the import
      callback();
    },
  ],
};
```

Other examples using different module formats:

**webpack.config.js**

```javascript
module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a `commonjs2` module located in `@scope/library`
      callback(null, '@scope/library', 'commonjs2');
    },
  ],
};
```

**webpack.config.js**

```javascript
module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a global variable called `nameOfGlobal`.
      callback(null, 'nameOfGlobal');
    },
  ],
};
```

**webpack.config.js**

```javascript
module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a named export in the `@scope/library` module.
      callback(null, ['@scope/library', 'namedexport'], 'commonjs');
    },
  ],
};
```

**webpack.config.js**

```javascript
module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a UMD module
      callback(null, {
        root: 'componentsGlobal',
        commonjs: '@scope/components',
        commonjs2: '@scope/components',
        amd: 'components',
      });
    },
  ],
};
```

### RegExp

Every dependency that matches the given regular expression will be excluded from the output bundles.

**webpack.config.js**

```javascript
module.exports = {
  //...
  externals: /^(jquery|\$)$/i,
};
```

In this case, any dependency named `jQuery`, capitalized or not, or `$` would be externalized.

### Combining syntaxes

Sometimes you may want to use a combination of the above syntaxes. This can be done in the following manner:

**webpack.config.js**

```javascript
module.exports = {
  //...
  externals: [
    {
      // String
      react: 'react',
      // Object
      lodash: {
        commonjs: 'lodash',
        amd: 'lodash',
        root: '_', // indicates global variable
      },
      // [string]
      subtract: ['./math', 'subtract'],
    },
    // Function
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        return callback(null, 'commonjs ' + request);
      }
      callback();
    },
    // Regex
    /^(jquery|\$)$/i,
  ],
};
```

W> [Default type](/configuration/externals/#externalstype) will be used if you specify `externals` without a type e.g. `externals: { react: 'react' }` instead of `externals: { react: 'commonjs-module react' }`.

For more information on how to use this configuration, please refer to the article on [how to author a library](/guides/author-libraries).

### byLayer

`function` `object`

Specify externals by layer.

**webpack.config.js**

```javascript
module.exports = {
  externals: {
    byLayer: {
      layer: {
        external1: 'var 43',
      },
    },
  },
};
```

## externalsType

`string = 'var'`

Specify the default type of externals. `amd`, `umd`, `system` and `jsonp` externals **depend on the [`output.libraryTarget`](/configuration/output/#outputlibrarytarget)** being set to the same value e.g. you can only consume `amd` externals within an `amd` library.

Supported types:

- `'amd'`
- `'amd-require'`
- `'assign'` - same as `'var'`
- [`'commonjs'`](#externalstypecommonjs)
- `'commonjs-module'`
- [`'global'`](#externalstypeglobal)
- `'import'` - uses `import()` to load a native EcmaScript module (async module)
- `'jsonp'`
- [`'module'`](#externalstypemodule)
- [`'import'`](#externalstypeimport)
- [`'module-import'`](#externalstypemodule-import)
- [`'node-commonjs'`](#externalstypenode-commonjs)
- [`'promise'`](#externalstypepromise) - same as `'var'` but awaits the result (async module)
- [`'self'`](#externalstypeself)
- `'system'`
- [`'script'`](#externalstypescript)
- [`'this'`](#externalstypethis)
- `'umd'`
- `'umd2'`
- [`'var'`](#externalstypevar)
- [`'window'`](#externalstypewindow)

**webpack.config.js**

```javascript
module.exports = {
  //...
  externalsType: 'promise',
};
```

### externalsType.commonjs

Specify the default type of externals as `'commonjs'`. Webpack will generate code like `const X = require('...')` for externals used in a module.

#### Example

```javascript
import fs from 'fs-extra';
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'commonjs',
  externals: {
    'fs-extra': 'fs-extra',
  },
};
```

Will generate into something like:

```javascript
const fs = require('fs-extra');
```

Note that there will be a `require()` in the output bundle.

### externalsType.global

Specify the default type of externals as `'global'`. Webpack will read the external as a global variable on the [`globalObject`](/configuration/output/#outputglobalobject).

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'global',
  externals: {
    jquery: '$',
  },
  output: {
    globalObject: 'global',
  },
};
```

Will generate into something like

```javascript
const jq = global['$'];
jq('.my-element').animate(/* ... */);
```

### externalsType.module

Specify the default type of externals as `'module'`. Webpack will generate code like `import * as X from '...'` for externals used in a module.

Make sure to enable [`experiments.outputModule`](/configuration/experiments/#experimentsoutputmodule) first, otherwise webpack will throw errors.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```js
module.exports = {
  experiments: {
    outputModule: true,
  },
  externalsType: 'module',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate into something like

```javascript
import * as __WEBPACK_EXTERNAL_MODULE_jquery__ from 'jquery';

const jq = __WEBPACK_EXTERNAL_MODULE_jquery__['default'];
jq('.my-element').animate(/* ... */);
```

Note that there will be an `import` statement in the output bundle.

### externalsType.import

<Badge text="5.94.0+" />

Specify the default type of externals as `'import'`. Webpack will generate code like `import('...')` for externals used in a module.

#### Example

```javascript
async function foo() {
  const jq = await import('jQuery');
  jq('.my-element').animate(/* ... */);
}
```

**webpack.config.js**

```js
module.exports = {
  externalsType: 'import',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate something like below:

```javascript
var __webpack_modules__ = {
  jQuery: (module) => {
    module.exports = import('jQuery');
  },
};

// webpack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jQuery')
  );
  jq('.my-element').animate(/* ... */);
}
```

Note that the output bundle will have an `import()` statement.

### externalsType.module-import

<Badge text="5.94.0+" />

Specify the default type of externals as `'module-import'`. This combines [`'module'`](#externalstypemodule) and [`'import'`](#externalstypeimport). Webpack will automatically detect the type of import syntax, setting it to `'module'` for static imports and `'import'` for dynamic imports.

Ensure to enable [`experiments.outputModule`](/configuration/experiments/#experimentsoutputmodule) first if static imports exist, otherwise, webpack will throw errors.

#### Example

```javascript
import { attempt } from 'lodash';

async function foo() {
  const jq = await import('jQuery');
  attempt(() => jq('.my-element').animate(/* ... */));
}
```

**webpack.config.js**

```js
module.exports = {
  externalsType: 'module-import',
  externals: {
    jquery: 'jquery',
    lodash: 'lodash',
  },
};
```

Will generate something like below:

```javascript
import * as __WEBPACK_EXTERNAL_MODULE_lodash__ from 'lodash';
const lodash = __WEBPACK_EXTERNAL_MODULE_jquery__;

var __webpack_modules__ = {
  jQuery: (module) => {
    module.exports = import('jQuery');
  },
};

// webpack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jQuery')
  );
  (0, lodash.attempt)(() => jq('.my-element').animate(/* ... */));
}
```

Note that the output bundle will have an `import` or `import()` statement.

When a module is not imported via `import` or `import()`, webpack will use the `"module"` externals type as a fallback. If you want to use a different kind of externals as a fallback, you can specify it with a function in the `externals` option. For example:

```js
module.exports = {
  externalsType: "module-import",
  externals: [
    function (
      { request, dependencyType },
      callback
    ) {
      if (dependencyType === "commonjs") {
        return callback(null, `node-commonjs ${request}`);
      }
      callback();
    },
  ]
```

### externalsType.node-commonjs

Specify the default type of externals as `'node-commonjs'`. Webpack will import [`createRequire`](https://nodejs.org/api/module.html#module_module_createrequire_filename) from `'module'` to construct a require function for loading externals used in a module.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```js
module.export = {
  experiments: {
    outputModule: true,
  },
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate into something like

```javascript
import { createRequire } from 'module';

const jq = createRequire(import.meta.url)('jquery');
jq('.my-element').animate(/* ... */);
```

Note that there will be an `import` statement in the output bundle.

This is useful when dependencies rely on Node.js built-in modules or require a CommonJS-style `require` function to preserve prototypes, which is necessary for functions like [`util.inherits`](https://nodejs.org/api/util.html#utilinheritsconstructor-superconstructor). Refer to [this issue](https://github.com/webpack/webpack.js.org/issues/7446) for more details.

For code that relies on prototype structures, like:

```js
function ChunkStream() {
  Stream.call(this);
}
util.inherits(ChunkStream, Stream);
```

You can use `node-commonjs` to ensure that the prototype chain is preserved:

```js
const { builtinModules } = require('module');

module.exports = {
  experiments: { outputModule: true },
  externalsType: 'node-commonjs',
  externals: ({ request }, callback) => {
    if (/^node:/.test(request) || builtinModules.includes(request)) {
      return callback(null, 'node-commonjs ' + request);
    }
    callback();
  },
};
```

This produces something like:

```js
import { createRequire as __WEBPACK_EXTERNAL_createRequire } from "node:module";
// ...
/***/ 2613:
/***/ ((module) => {

module.exports = __WEBPACK_EXTERNAL_createRequire(import.meta.url)("stream");

/***/ }),
```

This setup keeps the prototype structure intact, resolving issues with Node.js built-ins.

### externalsType.promise

Specify the default type of externals as `'promise'`. Webpack will read the external as a global variable (similar to [`'var'`](#externalstypevar)) and `await` for it.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'promise',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```javascript
const jq = await $;
jq('.my-element').animate(/* ... */);
```

### externalsType.self

Specify the default type of externals as `'self'`. Webpack will read the external as a global variable on the `self` object.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'self',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```javascript
const jq = self['$'];
jq('.my-element').animate(/* ... */);
```

### externalsType.script

Specify the default type of externals as `'script'`. Webpack will load the external as a script exposing predefined global variables with HTML `<script>` element. The `<script>` tag would be removed after the script has been loaded.

#### Syntax

```javascript
module.exports = {
  externalsType: 'script',
  externals: {
    packageName: [
      'http://example.com/script.js',
      'global',
      'property',
      'property',
    ], // properties are optional
  },
};
```

You can also use the shortcut syntax if you're not going to specify any properties:

```javascript
module.exports = {
  externalsType: 'script',
  externals: {
    packageName: 'global@http://example.com/script.js', // no properties here
  },
};
```

Note that [`output.publicPath`](/configuration/output/#outputpublicpath) won't be added to the provided URL.

#### Example

Let's load a `lodash` from CDN:

**webpack.config.js**

```js
module.exports = {
  // ...
  externalsType: 'script',
  externals: {
    lodash: ['https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js', '_'],
  },
};
```

Then use it in code:

```js
import _ from 'lodash';
console.log(_.head([1, 2, 3]));
```

Here's how we specify properties for the above example:

```js
module.exports = {
  // ...
  externalsType: 'script',
  externals: {
    lodash: [
      'https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js',
      '_',
      'head',
    ],
  },
};
```

Both local variable `head` and global `window._` will be exposed when you `import` `lodash`:

```js
import head from 'lodash';
console.log(head([1, 2, 3])); // logs 1 here
console.log(window._.head(['a', 'b'])); // logs a here
```

T> When loading code with HTML `<script>` tags, the webpack runtime will try to find an existing `<script>` tag that matches the `src` attribute or has a specific `data-webpack` attribute. For chunk loading `data-webpack` attribute would have value of `'[output.uniqueName]:chunk-[chunkId]'` while external script has value of `'[output.uniqueName]:[global]'`.

T> Options like `output.chunkLoadTimeout`, `output.crossOriginLoading` and `output.scriptType` will also have effect on the external scripts loaded this way.

### externalsType.this

Specify the default type of externals as `'this'`. Webpack will read the external as a global variable on the `this` object.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'this',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```javascript
const jq = this['$'];
jq('.my-element').animate(/* ... */);
```

### externalsType.var

Specify the default type of externals as `'var'`. Webpack will read the external as a global variable.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'var',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```javascript
const jq = $;
jq('.my-element').animate(/* ... */);
```

### externalsType.window

Specify the default type of externals as `'window'`. Webpack will read the external as a global variable on the `window` object.

#### Example

```javascript
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

**webpack.config.js**

```javascript
module.exports = {
  // ...
  externalsType: 'window',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```javascript
const jq = window['$'];
jq('.my-element').animate(/* ... */);
```

## externalsPresets

`object`

Enable presets of externals for specific targets.

| Option             | Description                                                                                                                                                                                                     | Input Type |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `electron`         | Treat common electron built-in modules in main and preload context like `electron`, `ipc` or `shell` as external and load them via `require()` when used.                                                       | boolean    |
| `electronMain`     | Treat electron built-in modules in the main context like `app`, `ipc-main` or `shell` as external and load them via `require()` when used.                                                                      | boolean    |
| `electronPreload`  | Treat electron built-in modules in the preload context like `web-frame`, `ipc-renderer` or `shell` as external and load them via require() when used.                                                           | boolean    |
| `electronRenderer` | Treat electron built-in modules in the renderer context like `web-frame`, `ipc-renderer` or `shell` as external and load them via `require()` when used.                                                        | boolean    |
| `node`             | Treat node.js built-in modules like `fs`, `path` or `vm` as external and load them via `require()` when used.                                                                                                   | boolean    |
| `nwjs`             | Treat `NW.js` legacy `nw.gui` module as external and load it via `require()` when used.                                                                                                                         | boolean    |
| `web`              | Treat references to `http(s)://...` and `std:...` as external and load them via `import` when used. **(Note that this changes execution order as externals are executed before any other code in the chunk)**.  | boolean    |
| `webAsync`         | Treat references to `http(s)://...` and `std:...` as external and load them via `async import()` when used **(Note that this external type is an `async` module, which has various effects on the execution)**. | boolean    |

Note that if you're going to output ES Modules with those node.js-related presets, webpack will set the default `externalsType` to [`node-commonjs`](#externalstypenode-commonjs) which would use `createRequire` to construct a require function instead of using `require()`.

**Example**

Using `node` preset will not bundle built-in modules and treats them as external and loads them via `require()` when used.

**webpack.config.js**

```js
module.exports = {
  // ...
  externalsPresets: {
    node: true,
  },
};
```
